docs: overhaul agent guidance by t3dotgg · Pull Request #4782 · pingdotgg/t3code

t3dotgg · 2026-07-28T20:37:27Z

The existing agent guidance did not capture enough of T3 Code's architecture, product constraints, or the operational hazards of developing the app from inside itself.

This replaces it with focused guidance on terminology, multi-surface changes, remote behavior, isolated dev state, verification, pull requests, architecture, and repository taste. The Markdown uses one physical line per paragraph and list item so editors can handle visual wrapping without noisy reflow diffs.

Validation: deno fmt --check --prose-wrap never AGENTS.md and git diff --check.

Authored with gpt-5.6-sol in the Codex harness.

Note

Low Risk
Documentation-only changes to AGENTS.md and README.md; no runtime, API, or security behavior changes.

Overview
Replaces the short AGENTS.md checklist with a full agent contributor guide aimed at coding inside T3 Code: product principles (open, performance, remote, multi-surface), shared glossary, operational hazards (safe process kills, isolated .t3 vs live userdata, no dev origin env vars), a hit every surface checklist, dev/test-data/verification defaults, PR etiquette, and a concise architecture + repo map. The old package-roles-only structure is folded into broader guidance; formatting is one physical line per paragraph/list item to reduce reflow noise.

README.md is updated in parallel to pitch T3 Code as an agent harness control surface, add Grok Build to supported providers and install warnings, expand the install-free npx t3@latest quick start, and soften the contribution stance (small fixes maybe; large features not).

^{Reviewed by Cursor Bugbot for commit 488374f. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Overhaul AGENTS.md and README.md contributor and product documentation

Rewrites AGENTS.md to replace task-focused guidelines with a full contributor guide covering architecture overview, coding standards, surfaces to verify, PR process, integration testing policy, and security guidance.
Updates README.md to reframe the project as an agent harness control surface, expand provider support (adding Grok Build), clarify the quick-start flow, and soften the contribution policy to accept small fixes.

^{Macroscope summarized 488374f.}

coderabbitai · 2026-07-28T20:37:35Z

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 43a6eac0-7329-484c-9453-f5cab2d42703

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch theo/agent-audit-guidance

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

macroscopeapp · 2026-07-28T20:44:00Z

Approvability

Verdict: Approved

Documentation-only changes to AGENTS.md and README.md with no runtime code impact. Updates agent guidance and project description text.

^{You can customize Macroscope's approvability policy. Learn more.}

Dismissing prior approval to re-evaluate 8229b08

Dismissing prior approval to re-evaluate 7e746b2

Dismissing prior approval to re-evaluate e7bdbec

@t3dotgg

## What's Changed * docs: overhaul agent guidance by @t3dotgg in pingdotgg/t3code#4782 **Full Changelog**: pingdotgg/t3code@v0.0.30-nightly.20260728.933...v0.0.30-nightly.20260728.935 Upstream release: https://github.com/pingdotgg/t3code/releases/tag/v0.0.30-nightly.20260728.935

@juliusmarminge

## What's Changed * Add OTA update checks to mobile settings by @juliusmarminge in pingdotgg/t3code#4686 * fix(mobile): threads load snapped to bottom on iOS by @t3dotgg in pingdotgg/t3code#4689 * feat: default sidebar v2 on for nightly and dev builds by @t3dotgg in pingdotgg/t3code#4491 * fix(web): 33 web UI fixes by @maxktz in pingdotgg/t3code#4700 * Make mobile Thread List v2 the default by @juliusmarminge in pingdotgg/t3code#4717 * Fix mobile showcase workflow without Clerk by @juliusmarminge in pingdotgg/t3code#4718 * Fix relay credential lookup for unlinked environments by @juliusmarminge in pingdotgg/t3code#4692 * Settle merged PR threads immediately by @t3dotgg in pingdotgg/t3code#4704 * feat(web): add maria's sidebar header artwork toggle by @maxktz in pingdotgg/t3code#4652 * feat(web): add appearance settings category by @maxktz in pingdotgg/t3code#4715 * fix(desktop): allow updater-controlled relaunch by @0x4bs3nt in pingdotgg/t3code#4721 * fix(web): prevent diff panel scroll jumping by @0x4bs3nt in pingdotgg/t3code#4724 * Link inline code file paths in chat markdown by @juliusmarminge in pingdotgg/t3code#4726 * Fix Android showcase capture and rebuild v2 queued rows by @juliusmarminge in pingdotgg/t3code#4730 * perf(server): negotiate permessage-deflate on the websocket by @t3dotgg in pingdotgg/t3code#4705 * docs: overhaul agent guidance by @t3dotgg in pingdotgg/t3code#4782 * Prevent sidebar row labels from truncating by @juliusmarminge in pingdotgg/t3code#4789 * perf(server): gzip large thread snapshots by @t3dotgg in pingdotgg/t3code#4788 * fix(web): stashed prompts now survive switching providers by @t3dotgg in pingdotgg/t3code#4787 * Fix Git ref refresh resource storms by @juliusmarminge in pingdotgg/t3code#4727 * perf(server): trim stale context-window rows and drop dead replay RPC by @t3dotgg in pingdotgg/t3code#4791 * fix(web): defer command palette filesystem navigation by @juliusmarminge in pingdotgg/t3code#2109 * fix(release): skip scripts during Vercel installs by @t3dotgg in pingdotgg/t3code#4796 * refactor(client): share filesystem browse navigation by @juliusmarminge in pingdotgg/t3code#4797 * fix(mobile): defer filesystem navigation by @juliusmarminge in pingdotgg/t3code#4799 * refactor(server): use native HTTP compression streams by @juliusmarminge in pingdotgg/t3code#4798 * Remove Connect waitlist and add GA announcement tooling by @juliusmarminge in pingdotgg/t3code#4691 **Full Changelog**: pingdotgg/t3code@v0.0.29...v0.0.30 ## What's Changed * Add OTA update checks to mobile settings by @juliusmarminge in pingdotgg/t3code#4686 * fix(mobile): threads load snapped to bottom on iOS by @t3dotgg in pingdotgg/t3code#4689 * feat: default sidebar v2 on for nightly and dev builds by @t3dotgg in pingdotgg/t3code#4491 * fix(web): 33 web UI fixes by @maxktz in pingdotgg/t3code#4700 * Make mobile Thread List v2 the default by @juliusmarminge in pingdotgg/t3code#4717 * Fix mobile showcase workflow without Clerk by @juliusmarminge in pingdotgg/t3code#4718 * Fix relay credential lookup for unlinked environments by @juliusmarminge in pingdotgg/t3code#4692 * Settle merged PR threads immediately by @t3dotgg in pingdotgg/t3code#4704 * feat(web): add maria's sidebar header artwork toggle by @maxktz in pingdotgg/t3code#4652 * feat(web): add appearance settings category by @maxktz in pingdotgg/t3code#4715 * fix(desktop): allow updater-controlled relaunch by @0x4bs3nt in pingdotgg/t3code#4721 * fix(web): prevent diff panel scroll jumping by @0x4bs3nt in pingdotgg/t3code#4724 * Link inline code file paths in chat markdown by @juliusmarminge in pingdotgg/t3code#4726 * Fix Android showcase capture and rebuild v2 queued rows by @juliusmarminge in pingdotgg/t3code#4730 * perf(server): negotiate permessage-deflate on the websocket by @t3dotgg in pingdotgg/t3code#4705 * docs: overhaul agent guidance by @t3dotgg in pingdotgg/t3code#4782 * Prevent sidebar row labels from truncating by @juliusmarminge in pingdotgg/t3code#4789 * perf(server): gzip large thread snapshots by @t3dotgg in pingdotgg/t3code#4788 * fix(web): stashed prompts now survive switching providers by @t3dotgg in pingdotgg/t3code#4787 * Fix Git ref refresh resource storms by @juliusmarminge in pingdotgg/t3code#4727 * perf(server): trim stale context-window rows and drop dead replay RPC by @t3dotgg in pingdotgg/t3code#4791 * fix(web): defer command palette filesystem navigation by @juliusmarminge in pingdotgg/t3code#2109 * fix(release): skip scripts during Vercel installs by @t3dotgg in pingdotgg/t3code#4796 * refactor(client): share filesystem browse navigation by @juliusmarminge in pingdotgg/t3code#4797 * fix(mobile): defer filesystem navigation by @juliusmarminge in pingdotgg/t3code#4799 * refactor(server): use native HTTP compression streams by @juliusmarminge in pingdotgg/t3code#4798 * Remove Connect waitlist and add GA announcement tooling by @juliusmarminge in pingdotgg/t3code#4691 **Full Changelog**: pingdotgg/t3code@v0.0.29...v0.0.30 Upstream release: https://github.com/pingdotgg/t3code/releases/tag/v0.0.30

t3dotgg added 2 commits July 28, 2026 13:30

first pass, poorly formatted

c036bb4

docs: normalize AGENTS.md formatting

0561bc0

github-actions Bot added vouch:trusted PR author is trusted by repo permissions or the VOUCHED list. size:L 100-499 changed lines (additions + deletions). labels Jul 28, 2026

docs: clarify agent verification guidance

c03e8b1

macroscopeapp Bot reviewed Jul 28, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

macroscopeapp Bot previously approved these changes Jul 28, 2026

View reviewed changes

docs: require permission for browser verification

8229b08

macroscopeapp Bot previously approved these changes Jul 28, 2026

View reviewed changes

docs: improve README product overview

7e746b2

macroscopeapp Bot previously approved these changes Jul 28, 2026

View reviewed changes

one more addition

e7bdbec

oops lol

488374f

macroscopeapp Bot approved these changes Jul 28, 2026

View reviewed changes

t3dotgg merged commit b64ae88 into main Jul 28, 2026
16 checks passed

t3dotgg deleted the theo/agent-audit-guidance branch July 28, 2026 21:10

This was referenced Jul 29, 2026

prepare stable release 2026.7.2900+tarik02 tarik02/t3code#84

Merged

prepare stable release 2026.7.2901 tarik02/t3code#95

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: overhaul agent guidance - #4782

docs: overhaul agent guidance#4782
t3dotgg merged 7 commits into
mainfrom
theo/agent-audit-guidance

t3dotgg commented Jul 28, 2026 •

edited by macroscopeapp Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 28, 2026 •

edited

Loading

Review skipped

Uh oh!

Uh oh!

macroscopeapp Bot commented Jul 28, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

t3dotgg commented Jul 28, 2026 • edited by macroscopeapp Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overhaul AGENTS.md and README.md contributor and product documentation

Uh oh!

coderabbitai Bot commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

Uh oh!

macroscopeapp Bot commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Approvability

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

t3dotgg commented Jul 28, 2026 •

edited by macroscopeapp Bot

Loading

coderabbitai Bot commented Jul 28, 2026 •

edited

Loading

macroscopeapp Bot commented Jul 28, 2026 •

edited

Loading